NCDF_PARSE

The NCDF_PARSE function recursively descends through a NetCDF-3 or NetCDF-4 file and creates an ordered hash containing object information and data.

Tip: The NetCDF-4 format is similar to the HDF5 format, so technically this routine can also parse HDF5 files. However, we recommend using H5_PARSE with HDF5 files.

Tip: For an example of reading GOES-16 data using NCDF_PARSE, see GOES-16 on a Map in the images gallery.

Example

The following example shows how to parse a file and to use implied print to view the tags of the ordered hash:

IDL> file = FILEPATH('sample.nc', SUBDIR=['examples','data'])

IDL> result = NCDF_PARSE(file)

IDL> result

IDL prints:

{

   "_NAME": "/usr/local/idl/examples/data/sample.nc",

   "_TYPE": "GROUP",

   "_FILE": "/usr/local/idl/examples/data/sample.nc",

   "_PATH": "/",

   "image": {

       "_NAME": "image",

       "_TYPE": "VARIABLE",

       "_PATH": "/",

       "_NDIMENSIONS": 2,

       "_DIMENSION_NAMES": ["y", "x"],

       "_DIMENSIONS": [768, 512],

       "_DATATYPE": "BYTE",

       "_DATA": "<unread>",

       "TITLE": {

           "_NAME": "TITLE",

           "_TYPE": "ATTRIBUTE",

           "_PATH": "/image",

           "_DATATYPE": "CHAR",

           "_LENGTH": 14,

           "_DATA": "New York City"

       }

},

"_NDIMENSIONS": 3,

"_DIMENSION_NAMES": ["x", "y", "z"],

"_DIMENSIONS": [512, 768, 0],

"_N_UNLIM_DIMS": 1,

"_UNLIM_DIM_NAMES": ["z"],

"_UNLIM_DIMS": [0],

"TITLE": {

    "_NAME": "TITLE",

    "_TYPE": "ATTRIBUTE",

    "_PATH": "/",

    "_DATATYPE": "CHAR",

    "_LENGTH": 26,

    "_DATA": "Incredibly Important Data"

},

"GALAXY": {

    "_NAME": "GALAXY",

    "_TYPE": "ATTRIBUTE",

    "_PATH": "/",

    "_DATATYPE": "CHAR",

    "_LENGTH": 10,

    "_DATA": "Milky Way"

},

"PLANET": {

    "_NAME": "PLANET",

    "_TYPE": "ATTRIBUTE",

    "_PATH": "/",

    "_DATATYPE": "CHAR",

    "_LENGTH": 6,

    "_DATA": "Earth"

   }

}

Here is an example of accessing the data within an ordered hash:

IDL> print, result['GALAXY', '_DATA'] ; use array indexing to retrieve this element

IDL prints:

Milky Way

Syntax

Result = NCDF_PARSE(File, [/ READ_DATA])

Return Value

The Result is an ordered hash containing the parsed file. The tags in the hash depend upon the object type, as outlined in the tables below.

Tags associated with the top-level hash

Tag

Description

_FILE

The filename to which the object belongs

Tags common to all object types

Tag

Description

_NAME

Object name (filename for the top level)

_TYPE

Object type. The possible values are GROUP, VARIABLE, or ATTRIBUTE.

_PATH

The full path within the file to the object. If the object is at the top level, then this field is set to '/'.

Tags associated with groups

Tag

Description

_NDIMENSIONS

Number of dimensions within the group

_DIMENSION_NAMES

Names of dimensions within the group. If the number of dimensions in the group is zero, then this field is set to an empty string.

_DIMENSIONS Size of all dimensions in the group. If the number of dimensions in the group is zero, then this field is set to -1.

_N_UNLIM_DIMS

Number of unlimited dimensions in the group

_UNLIM_DIM_NAMES

Names of unlimited dimensions in the group. If there are no unlimited dimensions in the group, then this field is set to an empty string.

_UNLIM_DIMS

Size of the unlimited dimension(s) in the group. If there are no unlimited dimensions in the group, then this field is set to -1.

Tags Associated with variables

Tag

Description

_NDIMENSIONS

Number of dimensions associated with the variable

_DIMENSION_NAMES

Names of the variable's dimensions

_DIMENSIONS

Size of the variable's dimensions

_DATATYPE

The variable data type. Possible data types are BYTE, CHAR, INT, LONG, FLOAT, or DOUBLE.

_DATA

If the READ_DATA keyword is set, this field will contain the data from the variable. Otherwise, it contains the string <unread>.

Tags associated with attributes

Tag

Description

_DATATYPE

Data type of the attribute. Possible values are BYTE, CHAR, INT, LONG, FLOAT, or DOUBLE.

_LENGTH

The number of values stored in the attribute. If the attribute is a string, the number of values indicates one more character than the string length to include the terminating null character. This is the NetCDF convention.

_DATA

The value of the attribute. The attribute value is always read regardless of whether the READ_DATA keyword is set.

Arguments

File

A string that specifies the file to be parsed.

Keywords

READ_DATA

If you set this keyword, all data from NetCDF variables will be read from the file. If you do not set this keyword, the _DATA field for variables will be set to the string '<unread>'.

Version History

8.5.2

Introduced

See Also

NCDF_IS_NCDF, NetCDF Overview, HDF_PARSE, H5_PARSE